Mensajes [Desarrolladores]

/v2/message/hsm/ - POST

Probar servicio

Permite iniciar una conversación con un cliente de manera proactiva utilizando un HSM.

Recuerde que todas las peticiones hechas a nuestra API deben ser autentificadas

Un HSM (Highly Structured Message) es una plantilla de mensajes de WhatsApp para enviar mensajes o notificaciones a los clientes. Para poder enviar un HSM, este debe estar previamente aprobado por Facebook. La persona que recibirá el mensaje debe haber aceptado que la contacten por Whatsapp (Opt-in). Adereso no se encarga de realizar este procedimiento.

Este servicio es para enviar HSM previamente cargados en Adereso. Debido a ciertas restricciones en la verificación de HSM aprobados la carga de estos se realiza de forma manual. Para cargar una nueva plantilla debe notificar al Equipo de Soporte o a su Ejecutivo Comercial de Adereso, indicando nombre, texto, idioma y el namespace (si corresponde).

Supongamos que nuestro HSM contiene el siguiente mensaje:

Estimado {1}, su orden número {2} se espera que llegue el día {3}

Un ejemplo de body para enviar un HSM y crear una conversación, en formato JSON:

{
  "account": "56900000000",
  "phone": "56911111111",
  "name": "template_name",
  "parameters": ["Carlos", "12345", "01/01/2020"]
}

Al teléfono del cliente, llegará el mensaje:

Estimado Carlos, su orden número 12345 se espera que llegue el día 01/01/2020

Donde los parámetros son:

Parámetros: El campo parameters debe incluir la cantidad exacta de argumentos necesarios para completar la plantilla especificada, además cada uno de ellos debe ser no vacío. No cumplir con esto puede causar que el mensaje no se envíe al cliente aun cuando el servicio responda con un código 200, debido a validaciones internas en WhatsApp rechazando el mensaje a pesar que haya dejado enviarlo.

La respuesta esperada tendrá la siguiente forma en caso de éxito:

{
  "status": 200,
  "message_id": "7a72e330d4cb11e9be4c",
  "ticket_id": "583dcb2855d0a46e438d0206"
}

En caso de que se intente enviar un mensaje con menos parámetros que los requeridos por el HSM, la respuesta será la siguiente:

{
  "status": 400,
  "msg": "Missing parameters for selected HSM"
}

Otros códigos de error comúnes son:

Desde nuestro sitio api-cluster.postcenter.io podrás hacerlo de la siguiente manera

Te mostramos un ejemplo de cómo hacerlo

/v2/message/create_conversation/ - POST

Probar servicio

Permite iniciar una conversación con un cliente de manera proactiva.

Mejores prácticas para WhatsApp: La persona que recibirá el mensaje debe saber que la van a contactar. De lo contrario es posible que reporte o bloquee la cuenta. Si muchos clientes lo hacen, WhatsApp puede bloquear el número de teléfono permanentemente.

No todos los números de WhatsApp conectados en Adereso tendrán permitido el envío proactivo de mensajes. Para un mejor manejo, usted debe definir desde la aplicación qué cuentas se utilizarán para envío de mensajes proactivo y cuáles no. Se recomienda que las cuentas proactivas se consideren desechables. Usted además puede monitorear cuántos envíos proactivos ha realizado cada cuenta por mes y cuándo se acerca a un límite peligroso. En este caso recomendamos habilitar más números proactivos y dividir la carga.

Para ver esta configuración, debe tener permiso de administrador y luego ir a Administración / Canales tab Whatsapp, en la cuenta a configura hacer click en Configuración luego Opciones de Whatsapp y luego Activar mensajes proactivos

Ejemplo de body para crear la conversación, en formato JSON:

{
  "phone": "56912349876",
  "user_name": "Carlos Soto",
  "account_id": "au2geg72gs",
  "message": "Hola Carlos, bienvenido a nuestra tienda"
}

Donde los parámetros son:

En ocasiones ciertas acciones de agentes pueden complejizar el flujo de una integración, que requiere que un ticket mantenga su estado o no pueda ser eliminado.

En Adereso un agente puede unir dos tickets. Cuando se realiza esta acción, se unifica en uno de los dos tickets, toda la información de ambos, incluyendo mensajes, comentarios o clasificaciones del ticket. El otro se elimina. Este puede ser un comportamiento no deseable en algunos casos de negocio, por lo que existe el parámetro no_manual_merge, que impide que el ticket creado pueda ser fusionado y en consecuencia potencialmente eliminado.

Así mismo, un agente puede abrir o cerrar un ticket múltiples veces. En ocasiones esto puede provocar que el ticket tenga un estado no deseado de cara a una integración. Para garantizar que un ticket una vez cerrado, siempre se mantendrá así, usted puede utilizar el parámetro no_manual_reopen, que impedirá a los agentes re-abrir el ticket, garantizando su estado.

En el caso de que necesitemos que el ticket creado no pueda ser fusionado o re-abierto, existen los campos no_manual_merge y no_manual_reopen. Lo anterior es relevante si el flujo que queremos implementar con los tickets de Adereso requiere mantener ciertas condiciones.

La respuesta esperada tendrá la siguiente forma en caso de éxito:

{
  "status": 200,
  "ticket_id": "583dcb2855d0a46e438d0206"
}

En caso de que se intente enviar un mensaje utilizando una cuenta que no tiene permitido enviar mensajes proactivos, la respuesta será la siguiente:

{
  "status": 202,
  "msg": "This account doesnot allow proactive messaging. Please configure at least one account to be allowed to send proactive messages in Admin / Channels / Whatsapp select account and then Configurations > Enable Proactive Messaging"
}

/v2/message/ - POST

Probar servicio

El servicio de Publicar Mensajes permite responder un mensaje a un cliente dentro de un determinado ticket de atención. Si no se provee un client_id, el mensaje se enviará al primer cliente que participe en el ticket y se responderá al último mensaje del ticket.

Por defecto, solo se pueden responder mensajes privados, por lo que Adereso buscará el primer mensaje privado que encuentre y responderá a ese.

Si requiere enviar mensajes públicos, lo puede hacer enviando el parámetro private_only en false. De esta forma, si se encuentra un mensaje público primero, se respondera a ese mensaje.

Si Adereso no encuentra mensajes privados del cliente y no se usa el flag private_only o se establece en true usted obtendrá el código de error 403 - FORBDDEN. Si no se encuentra ningún mensaje, recibirá un mensaje de error 404 - NOT FOUND.

Solo mensajes de Adereso: Usted sólo puede responder mensajes que han pasado por Adereso y estén vinculados a las cuentas de su empresa en nuestra plataforma.

Un ejemplo de respuesta después de un envío exitoso será:

{
  "status": 200,
  "message": "Message sent to carlos@soto.cl"
}

La respuesta se conforma de los siguientes campos:

Usted debe enviar los siguientes parámetros en formato JSON en el body de su petición:

Un ejemplo es:

{
  "ticket_id": "583dcb2855d0a46e438d0206",
  "message": "Este es un mensaje para un cliente"
}

Si todo es correcto, la respuesta esperada será:

{
  "status": 200,
  "message": "Message sent to carlos@soto.cl"
}

El mensaje en este ejemplo se habrá enviado al primer cliente en el ticket 583dcb2855d0a46e438d0206 de manera privada.

Otro ejemplo puede ser:

{
  "ticket_id": "583dcb2855d0a46e438d0206",
  "client_id": "546b9b2720a9f1301050fec3",
  "message": "Este es un mensaje para un cliente",
  "private_only": false
}

Donde se explicita que el cliente 546b9b2720a9f1301050fec3 recibirá el mensaje en el ticket 583dcb2855d0a46e438d0206 pudiendo ser que su respuesta aparezca pública o privada, dependiendo de cuál sea más reciente.